/*
 * Course:    CS 590 Web Services
 * Semseter:  Spring 2009
 * Professor: Sedlemeyer
 * Project:   CHEAT (Code Help Educational Assignment Tool)
 * Due Date:  May 1, 2009
 * Team:      Sarcasm
 *            (Baker, Jason; Mitchell, Robin; Shie, Keith)
 */
package cheat.authentication;


import cheat.entities.Person;
import cheat.entities.RegisteredUser;
import cheat.entities.UserSession;
import javax.ejb.Local;


/**
 * Provides the local interface to the SecurityManagerBean.
 *
 * The security manager contains the functionality related to
 * security/user management.
 *
 * @author Keith Shie
 */
@Local
public interface SecurityManagerLocal {

  /**
   * Create a new session for the user.
   *
   * <p>This implementation allows the same user to have multiple
   * sessions active at the same time.</p>
   *
   * <p>Ideally, this method would not be part of a public API.  However, we
   * need to gain control over the transaction so that we can force the
   * persistance layer to generate the PK for the underlying UserSession
   * Entity.  Providing this method as part of the public API is the most
   * straight forward way to gain this control.</p>
   *
   * @param user user for which this session is being created.
   * @return UserSession which was created.
   */
  UserSession createNewSession( RegisteredUser user );


  /**
   * Create a new Person.
   *
   * <p>Ideally, this method would not be part of a public API.  However, we
   * need to gain control over the transaction so that we can force the
   * persistance layer to generate the PK for the underlying UserSession
   * Entity.  Providing this method as part of the public API is the most
   * straight forward way to gain this control.</p>
   *
   * @param person Person to be created.
   * @return The newly created Person.
   */
  Person createNewPerson( Person person );


  /**
   * Update the last access time of the specified UserSession.
   *
   * <p>Ideally, this method would not be part of a public API.  However, we
   * need to gain control over the transaction so that we can force the
   * persistance layer to update the session regardless of any subsequent actions
   * (transaction rollbacks or other errors).  Providing this method as part
   * of the public API is the most straight forward way to gain this
   * control.</p>
   *
   * @param session UserSession to update.
   */
  void updateSessionLastAccess( UserSession session );


  /**
   * Utility method to retrieve the UserSession with the specified
   * <code>sessionId</code>.
   *
   * @param sessionId Id of the UserSession to retrieve.
   * @return Matching UserSession
   * @throws cheat.authentication.InvalidSessionException
   */
  UserSession getSession( int sessionId ) throws InvalidSessionException;
}
